home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / drag.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  8.0 KB  |  242 lines
  1. dopus5.library/Drag Routines                     dopus5.library/Drag Routines
  2.  
  3.     No, this isn't a new form of software-based cabaret act. The drag
  4.     routines in the dopus5.library make it easy for you to implement your
  5.     own drag and drop system.
  6.  
  7.     The DragInfo structure is the key of this system. Calling the
  8.     GetDragInfo() function will create one of these structures, and you
  9.     use it in all subsequent calls.
  10.  
  11.     The important fields of the DragInfo structure are :
  12.  
  13.         flags     You can set flags to modify the behavior of dragged images.
  14.  
  15.                   DRAGF_OPAQUE indicates that the drag image should be opaque;
  16.                   that is, colour 0 does not allow the background to show
  17.                   through.
  18.  
  19.                   DRAGF_NO_LOCK indicates that the drag routines should not
  20.                   lock the screen layers themselves.
  21.  
  22.                   DRAGF_TRANSPARENT indicates that the drag image should be
  23.                   transparent. Used in conjunction with DRAGF_OPAQUE, it
  24.                   allows you to create irregular shaped images.
  25.  
  26.         drag_rp   This is a RastPort that you can use to draw into the
  27.                   drag image.
  28.  
  29.     The other fields of the DragInfo structure can be used by you, but
  30.     normally they should be left alone.
  31.  
  32.     The usual process of dragging an image is :
  33.  
  34.         1. GetDragInfo()
  35.         2. Either render into di->drag_rp or call GetDragImage()
  36.         3. Call GetDragMask() if you rendered directly
  37.         4. If you set DRAGF_NO_LOCK, LockLayers()
  38.         5. Multiple calls to ShowDragImage() to make the image visible
  39.            and move it around (in response to mouse movements)
  40.         6. FreeDragInfo() to remove the image
  41.         7. If DRAGF_NO_LOCK was set, UnlockLayers()
  42.  
  43.     The Amiga OS has a bug which can cause a deadlock if another task attempts
  44.     to call LockLayers() while you have them locked. If you are dragging over
  45.     the entire screen rather than an individual window, you will need to take
  46.     additional steps to prevent this deadlock.
  47.  
  48.     You need to set up a timer event, roughly every half second or so (the
  49.     dopus5.library timer routines are ideal for this purpose). You also need
  50.     to have the IDCMP_INTUITICKS flag set for your window. You then must
  51.     keep a count of the number of IDCMP_INTUITICKS messages received. Every
  52.     time your periodic timer event comes around, you must examine this count
  53.     to see if it has changed. As INTUITICKS are sent roughly every 10th of
  54.     a second, one or more should have been received between each of your
  55.     timer events. If no INTUITICKS were received, it's a fair bet that
  56.     Intuition has deadlocked itself, and you should immediately call
  57.     UnlockLayers() (or HideDragImage()) to unfreeze the system.
  58.  
  59. dopus5.library/FreeDragInfo                       dopus5.library/FreeDragInfo
  60.  
  61.     NAME
  62.         FreeDragInfo - frees a DragInfo structure
  63.  
  64.     SYNOPSIS
  65.         FreeDragInfo(drag)
  66.                       A0
  67.  
  68.         void FreeDragInfo(DragInfo *);
  69.  
  70.     FUNCTION
  71.         This function removes a drag image from the display if it is still
  72.         visible, and frees the DragInfo structure.
  73.  
  74.     INPUTS
  75.         drag - structure to free
  76.  
  77.     SEE ALSO
  78.         GetDragInfo()
  79.  
  80. dopus5.library/GetDragImage                       dopus5.library/GetDragImage
  81.  
  82.     NAME
  83.         GetDragImage - pick up on-screen imagery to drag
  84.  
  85.     SYNOPSIS
  86.         GetDragImage(drag, x, y)
  87.                       A0  D0 D1
  88.  
  89.         void GetDragImage(DragInfo *, long, long);
  90.  
  91.     FUNCTION
  92.         This routine copies on-screen image data into the rastport of the
  93.         specified DragInfo structure. If the drag image is visible when this
  94.         routine is called, it is cleared before the data is copied.
  95.  
  96.     INPUTS
  97.         drag - DragInfo structure
  98.         x - x-position on screen
  99.         y - y-position on screen
  100.  
  101.     RESULT
  102.         The image data is copied from the Bitmap of the Window that was
  103.         specified when the drag image was created. This routine calls
  104.         GetDragMask() automatically.
  105.  
  106.     SEE ALSO
  107.         GetDragInfo()
  108.  
  109. dopus5.library/GetDragInfo                         dopus5.library/GetDragInfo
  110.  
  111.     NAME
  112.         GetDragInfo - create a DragInfo structure
  113.  
  114.     SYNOPSIS
  115.         GetDragInfo(window, rastport, width, height, need_gels)
  116.                       A0       A1       D0     D1       D2
  117.  
  118.         DragInfo *GetDragInfo(struct Window *, struct RastPort *,
  119.                               long, long, long);
  120.  
  121.     FUNCTION
  122.         Creates a DragInfo structure that is used to implement drag and drop.
  123.         Drags are inherently attached to a particular RastPort (usually either
  124.         a screen's or a window's). The drag system is implemented using BOBs,
  125.         which require a GelsInfo structure to be attached to the destination
  126.         RastPort. This routine can do this for you if you desire.
  127.  
  128.     INPUTS
  129.         window - Window to attach BOB to (or NULL if rastport is supplied)
  130.         rastport - RastPort to attach BOB to (if not a window)
  131.         width - width of drag image
  132.         height - height of drag image
  133.         need_gels - set to TRUE if you would like this routine to allocate
  134.                     and initialise a GelsInfo automatically
  135.  
  136.     RESULT
  137.         If successful, a DragInfo structure is returned. Nothing is displayed
  138.         on-screen; you must create the image and display it using the other
  139.         library calls. Once you have the DragInfo structure, you can
  140.         initialise the 'flags' field as described in the introduction.
  141.  
  142.     SEE ALSO
  143.         FreeDragInfo()
  144.  
  145. dopus5.library/GetDragMask                         dopus5.library/GetDragMask
  146.  
  147.     NAME
  148.         GetDragMask - build mask for drag image
  149.  
  150.     SYNOPSIS
  151.         GetDragMask(drag)
  152.                      A0
  153.  
  154.         void GetDragMask(DragInfo *);
  155.  
  156.     FUNCTION
  157.         Once you have created the image you want to drag, you must call
  158.         this function. This builds the shadow mask used to drag the image,
  159.         and is necessary for the image to be displayed correctly.
  160.  
  161.     INPUTS
  162.         drag - DragInfo structure to build mask for
  163.  
  164.     SEE ALSO
  165.         GetDragInfo()
  166.  
  167. dopus5.library/HideDragImage                     dopus5.library/HideDragImage
  168.  
  169.     NAME
  170.         HideDragImage - remove a drag image from the display
  171.  
  172.     SYNOPSIS
  173.         HideDragImage(drag)
  174.                        A0
  175.  
  176.         void HideDragImage(DragInfo *);
  177.  
  178.     FUNCTION
  179.         This routine removes a visible drag image from the display.
  180.  
  181.     INPUTS
  182.         drag - DragInfo structure
  183.  
  184.     SEE ALSO
  185.         ShowDragImage()
  186.  
  187. dopus5.library/ShowDragImage                     dopus5.library/ShowDragImage
  188.  
  189.     NAME
  190.         ShowDragImage - display a drag image
  191.  
  192.     SYNOPSIS
  193.         ShowDragImage(drag, x, y)
  194.                        A0  D0 D1
  195.  
  196.         void ShowDragImage(DragInfo *, long, long);
  197.  
  198.     FUNCTION
  199.         This routine displays a drag image at a given location. The image is
  200.         displayed in the RastPort that was supplied to the GetDragInfo() call.
  201.         If the image was not already displayed, it is added to the display.
  202.         If it was, it is removed from its current position and redisplayed in
  203.         the new location. This is the main call used to move an image around
  204.         the screen.
  205.  
  206.     INPUTS
  207.         drag - DragInfo structure to display
  208.         x - x position in rastport
  209.         y - y position in rastport
  210.  
  211.     SEE ALSO
  212.         GetDragInfo(), HideDragImage()
  213.  
  214. dopus5.library/StampDragImage                   dopus5.library/StampDragImage
  215.  
  216.     NAME
  217.         StampDragImage - stamp drag image onto the screen
  218.  
  219.     SYNOPSIS
  220.         StampDragImage(drag, x, y)
  221.                         A0  D0 D1
  222.  
  223.         void StampDragImage(DragInfo *, long, long);
  224.  
  225.     FUNCTION
  226.         This routine stamps the drag image onto the bitmap at the given
  227.         location. Using this function would allow you to "paint" with the
  228.         drag image.
  229.  
  230.     INPUTS
  231.         drag - DragInfo structure
  232.         x - x position to stamp image at
  233.         y - y position to stamp image at
  234.  
  235.     RESULT
  236.         The image is drawn into the RastPort that was supplied in the
  237.         GetDragInfo() call.
  238.  
  239.     SEE ALSO
  240.         GetDragInfo(), ShowDragImage()
  241.  
  242.